The Atari Compendium

home *** CD-ROM | disk | FTP | other *** search

/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / mint / mntdoc01.zoo / mintdoc / pure_src / lib3.src < prev next >

Wrap

C/C++ Source or Header | 1993-03-03 | 62.3 KB | 1,855 lines

screen( capsensitive("a64l"), capsensitive("l64a")) NAME a64l, l64a - convert between long integer and base-64 ASCII string SYNOPSIS #include <support.h> long a64l(const char *s); char *l64a(long l); DESCRIPTION These functions are used to maintain numbers stored in base-64 ASCII characters. This is a notation by which long integers can be represented by up to six characters; each character represents a "digit" in a radix-64 notation. The characters used to represent "digits" are . for 0, / for 1, 0 through 9 for 2-11, A through Z for 12-37, and a through z for 38-63. a64l takes a pointer to a null-terminated base-64 representation and returns a corresponding long value. If the string pointed to by s contains more than six characters, a64l will use the first six. a64l scans the character string from left to right, decoding each character as a 6 bit radix-64 number. If the string contains illegal characters, -1 is returned and errno is set to EBADARG. l64a takes a long argument and returns a pointer to the corresponding base-64 representation. If the argument is 0, a64l returns a pointer to a null string. If the argument is smaller than zero, a pointer to a null string is returned and errno is set to EBADARG. CAVEATS The value returned by l64a is a pointer into a static buffer, the contents of which are overwritten by each call. The value returned by a64l may be incorrect if the value is too large; for that reason, only strings that resulted from a call to l64a should be used to call a64l. Maybe these calls should use unsigned long values, but longs are used here to retain compatibility with UN*X System V.\end screen( capsensitive("abort")) NAME abort - abort the current program SYNOPSIS #include <stdlib.h> void abort(void); DESCRIPTION abort does the work of \#exit\#, but instead of just exiting, abort causes SIGABRT to be sent to the calling process. After sending the signal, abort does an exit(127). Whether or not the \#atexit\# routines will be called seems to be somewhat timing-sensitive. RETURN VALUES abort does not return. SEE ALSO \#exit\#, \#kill\#, \#signal\#\end screen( capsensitive("abs"), capsensitive("labs")) NAME abs, labs - return integer or long absolute value SYNOPSIS #include <stdlib.h> int abs(int i); long labs(long i); DESCRIPTION abs returns the absolute value of its integer operand. labs returns the absolute value of its long operand. SEE ALSO \#fabs\# CAVEAT In two's-complement representation, the absolute value of the negative integer or long with the largest magnitude is undefined. This error is not trapped in this implementation.\end screen( capsensitive("bsearch")) NAME bsearch - binary search a sorted table SYNOPSIS #include <stdlib.h> void *bsearch(const void *key, const void *base, size_t total_elems, size_t elem_size, int (*compare)(const void *one, const void *two)); DESCRIPTION bsearch is a binary search routine generalized from Knuth (6.2.1) Algorithm B. It returns a pointer into a table indicating where a datum may be found. The table must be previously sorted in increasing order according to a provided comparison function. - key points to a datum instance to be sought in the table. - base points to the element at the base of the table. - total_elems is the number of elements in the table. - elem_size is the size, in bytes, of each element in the table. - compare is the name of the comparison function, which is called with two arguments that point to the elements being compared. As the function must return an integer less than, equal to, or greater than zero, so must the first argument to be considered be less than, equal to, or greater than the second. EXAMPLE The example below searches a table containing pointers to nodes consisting of a string and its length. The table is ordered alphabetically on the string in the node pointed to by each entry. This code fragment reads in strings and either finds the corresponding node, in which case it prints out the string and its length, or it prints an error message. #include <stdio.h> #include <stdlib.h> #include <string.h> #define TABSIZE 1000 struct node /* These are stored in the table */ { char *string; int length; }; struct node table[TABSIZE]; /* Table to be searched */ . . . { struct node *node_ptr, node; int node_compare(const struct *node1, const struct *node2); char str_space[20]; /* space to read string into */ . . . node.string = str_space; while (scanf("%s", node.string) != EOF) { node_ptr = (struct node *)bsearch(&node, table, TABSIZE, sizeof(struct node), node_compare); if (node_ptr != NULL) printf("string = %20s, length = %d\\n", node_ptr->string, node_ptr->length); else printf("not found: %s\\n", node.string); } } /* Compare two nodes based on an alphabetical */ /* ordering of the string field. */ int node_compare(const void *table_node, const void *key_node) { const struct node *table = (const struct node *)table_node; const struct node *key = (const struct node *)key_node; return(strcmp(table->string, key->string)); } SEE ALSO \#qsort\# NOTES The comparison function need not compare every byte, so arbitrary data may be contained in the elements in addition to the values being compared. A NULL pointer is returned if the key cannot be found in the table.\end screen( capsensitive("clock")) NAME clock - report CPU time used SYNOPSIS #include <time.h> clock_t clock(void); DESCRIPTION clock returns the amount of time passed (in 200Hz clock ticks) since the program was started. SEE ALSO \#times\#, \#getrusage\# BUGS This function is hopelessly different from the UN*X function clock, which returns CPU time used by the program and all its terminated children, instead of real time elapsed since the program started.\end screen( capsensitive("opendir"), capsensitive("readdir"), capsensitive("telldir"), capsensitive("seekdir"), capsensitive("rewinddir"), capsensitive("closedir")) NAME directory, opendir, readdir, telldir, seekdir, rewinddir, closedir - directory operations SYNOPSIS #include <dirent.h> DIR *opendir(const char *dirname); struct dirent *readdir(DIR *dirp); off_t telldir(DIR *dirp); void seekdir(DIR *dirp, off_t loc); void rewinddir(DIR *dirp); int closedir(DIR *dirp); DESCRIPTION opendir opens the directory named by dirname and associates a directory stream with it. opendir returns a pointer to be used to identify the directory stream in subsequent operations. A NULL pointer is returned if dirname cannot be accessed or is not a directory, or if it cannot \#malloc\# enough memory to hold the whole thing. readdir returns a pointer to the next directory entry. It returns NULL upon reaching the end of the directory or detecting and invalid seekdir operation. telldir returns the current location associated with the named directory stream. seekdir sets the position of the next readdir operation on the directory stream. The new position reverts to the one associated with the directory stream when the telldir operation was performed. Values returned by telldir are good only for the lifetime of the DIR pointer from which they are derived. If the directory is closed and then reopened, the telldir value may be invalidated due to changes in the directory. rewinddir resets the position of the named directory stream to the beginning of the directory. It also causes the directory stream to refer to the current state of the corresponding directory, as a call to opendir would have done. closedir closes the named directory stream and frees the structure associated with the DIR pointer. RETURN VALUES opendir returns a pointer of type DIR on success. On failure, it returns NULL and sets errno to indicate the error. readdir returns a pointer of object type struct dirent on success. On failure, it returns NULL and sets errno to indicate the error. When the end of the directory is encountered, readdir returns NULL and leaves errno unchanged. The dirent structure is defined in <dirent.h> and contains the following fields of interest: struct dirent { long d_ino; /* garbage under TOS emulation */ off_t d_off; /* position in directory */ short d_reclen; /* length of d_name */ ... /* various TOS-emulation fields */ char *d_name; /* name of the current file */ }; closedir returns 0 on succes, EIHNDL on failure. telldir returns the current location associated with the specified directory stream. EXAMPLE Sample code which searches a directory for entry `name' is: dirp = opendir("."); for (dp = readdir(dirp); dp != NULL; dp = readdir(dirp)) if (!strcmp(dp->d_name, name)) { closedir(dirp); return (FOUND); } closedir(dirp); return (NOT_FOUND); SEE ALSO \#Dopendir\#, \#Dreaddir\#, \#Dclosedir\#; these system calls are used in the implementation of the directory routines. NOTES As memory is allocated at every call to opendir, every call to opendir should be matched by a corresponding call to closedir. When MiNT is not active, readdir calls are emulated under TOS. When that happens, various fields in the dirent structure are used that are undefined when MiNT is active. It is therefore advisable not to use those fields. Because of an error in the mintlibs and a change in MiNT 0.97, programs using readdir from the mintlibs pl 24 or below will die in MiNT 0.97 or higher.\end screen( capsensitive("exec") capsensitive("execl"), capsensitive("execv"), capsensitive("execle"), capsensitive("execlp"), capsensitive("execve"), capsensitive("execvp")) NAME execl, execv, execle, execlp, execve, execvp - execute a file SYNOPSIS #include <unistd.h> int execl(char *path, ...); int execv(char *path, char *argv[]); int execle(char *path, ...); int execlp(char *file, ...); int execve(char *path, char *argv[], char *envp[]); int execvp(char *file, char *argv[]); DESCRIPTION These routines transform the calling process into a new process. The program indicated by `path' or `file' is loaded, then run. There can be no return from a succesful exec call. These calls differ in the following ways: - execl, execle and execlp are called when the number of arguments is known in advance, whereas execv, execve and execvp take an argument vector. - execl, execv, execle and execve are called with the full path name of the program to be run, whereas execlp and execvp are called with a filename that is searched on the user's search path and that may be extended with the filename extensions ".ttp", ".tos" and ".prg". - execl, execv, execlp and execvp pass the parent's environment to the new process, whereas execle and execve take a pointer to an environment vector as their final argument. The last argument to the execl, execle and execlp functions should be a NULL pointer. An argument vector argv as used in execv, execve and execvp is a pointer to a null-terminated array of character pointers to null-terminated character strings. These strings constitute the argument list to be made available to the new process. By convention, at least one argument must be present in this array, and the first element of this array should be the name of the executed program. For execv and execve this is the last component of the path argument; for execvp this is the file argument. The environment vector envp as used in execle and execve is also a pointer to a null-terminated array of character pointers to null-terminated strings. These strings pass information to the new process which are not directly arguments to the command. If envp is NULL, a copy of the parent process' environment is passed. Signals set to the default action (SIG_DFL) in the calling process image are set to the default action in the new process. Signals set to be ignored (SIG_IGN) by the calling process are ignored by the new process. Signals set to be caught by the calling process are reset to the default action in the new process. Signals set to be blocked in the calling process remain blocked in the new process, regardless of changes to the signal action. RETURN VALUES These functions returns to the calling process only on failure, for instance if the program called could not be found, if it was not executable, or if not enough memory was available, in which case -1 is returned and errno is set to indicate the error. EXAMPLES This will execute the program /bin/date or fail: execl("/bin/date", "date", NULL); This will search the program sh and then execute it; it will fail only if sh, sh.tos, sh.ttp and sh.prg could not be found: execlp("sh", "sh", "-c", commandline, NULL); This will call /bin/test using an already constructed argument vector and an already constructed environment vector, and fail if /bin/test could not be found: execve("/bin/test", my_argv, my_envp); SEE ALSO \#fork\#, \#signal\#, \#tfork\#, \#vfork\# \#_spawnve\# - this is the library call underlying all these routines. NOTES When MiNT is not active, these library calls call a child process and then \#_exit\# after the child has finished; only when MiNT is active, the current process is truly transformed into a new one. On Un*x, execve is a system call, while the rest of these calls are library routines. Under MiNT, it's all done in the library.\end screen( capsensitive("fclose"), capsensitive("fflush")) NAME fclose, fflush - close or flush a stream SYNOPSIS #include <stdio.h> int fclose(FILE *stream); int fflush(FILE *stream); DESCRIPTION fclose writes out any buffered data for the named stream, and closes the named stream. Buffers allocated by the standard input/output system are freed. fclose is performed automatically for all open files upon calling \#exit\#. fflush writes any unwritten data for an output stream or an update stream in which the most recent operation was not input to be delivered to the host environment to the file; otherwise it is ignored. The named stream remains open. RETURN VALUES fclose returns: 0 on success. EOF if any error (such as trying to write to a file that has not been opened for writing) was detected. fflush returns: 0 on success or if the file wasn't open. EOF if an error was detected while writing the data. SEE ALSO \#close\#, \#exit\#, \#fopen\#, \#setbuf\#\end screen( capsensitive("ferror"), capsensitive("feof"), capsensitive("clearerr"), capsensitive("fileno")) NAME ferror, feof, clearerr, fileno - stream status enquiries SYNOPSIS #include <stdio.h> int ferror(FILE *stream); int feof(FILE *stream); void clearerr(FILE *stream); int fileno(FILE *stream); DESCRIPTION ferror returns non-zero when an I/O error has previously occurred reading from or writing to the named stream, otherwise zero. feof returns non-zero when EOF has previously been detected reading the named input stream, otherwise zero. clearerr resets the error indicator and EOF indicator to zero on the named stream. fileno returns the integer file descriptor associated with the named stream. SEE ALSO \#open\#, \#fopen\# NOTE All these functions are implemented as macros; they cannot be declared or redeclared.\end screen( capsensitive("fopen"), capsensitive("freopen"), capsensitive("fdopen")) NAME fopen, freopen, fdopen - open a stream SYNOPSIS #include <stdio.h> FILE *fopen(const char *filename, const char *type); FILE *freopen(const char *filename, const char *type, FILE *stream); FILE *fdopen(int fd, const char *type); DESCRIPTION fopen opens the file named by filename and associates a stream with it. If the open succeeds, fopen returns a pointer to be used to identify the stream in subsequent operations. filename points to a character string that contains the name of the file to be opened. type is a character string starting with one the following values: r - open for reading w - truncate or create for writing a - append: open for writing at end of file, or create for writing r+ - open for update (reading and writing) w+ - truncate or create for update a+ - append; open or create for update at EOF After one of the above, type may be followed by: t - open file in text mode (translate \\r\\n to \\n when reading, and \\n to \\r\\n when writing) b - open file in binary mode (no \\r, \\n translation) If neither 't' nor 'b' is set, the file will be opened in the default mode set by the user. If the environment variable UNIXMODE contains the letter 'b', the default mode will be binary; otherwise, the default mode is text mode. freopen opens the file named by filename and associates the stream pointed to by stream with it. The type argument is used just as in fopen. The original stream is closed, regardless of whether the open ultimately succeeds. If the open succeeds, freopen returns the original value of stream. freopen is typically used to attach the preopened streams associated with stdin, stdout, and stderr to other files. fdopen associates a stream with the file descriptor fd. File descriptors are obtained from calls like \#open\#, \#dup\#, \#creat\#, or \#pipe\#, which open files but do not return streams. Streams are necessary input for many of the library routines. The type of the stream must agree with the access permissions of the open file. When a file is opened for update, both input and output may be done on the resulting stream. However, output may not be directly followed by input without an intervening \#fseek\# or \#rewind\#, and input may not be directly followed by output without an intervening \#fseek\#, \#rewind\#, or an input operation which encounters EOF. RETURN VALUES On success, fopen, freopen, and fdopen return a pointer to FILE which identifies the opened stream. On failure, they return NULL. SEE ALSO \#open\#, \#pipe\#, \#fclose\#, \#fseek\# BUGS The library allows only a limited number of streams to be open at the same time. Thus, a program may run out of streams even though the system is not yet out of memory.\end screen( capsensitive("fread"), capsensitive("fwrite")) NAME fread, fwrite - buffered binary input/output SYNOPSIS #include <stdio.h> size_t fread (void *ptr, size_t size, size_t nitems, FILE *stream); size_t fwrite (const void *ptr, size_t size, size_t nitems, FILE *stream); DESCRIPTION fread reads, into a block pointed to by ptr, nitems items of data from the named input stream stream, where an item of data is a sequence of bytes (not necessarily terminated by a null byte) of length size. It returns the number of items actually read. fread stops reading if an end-of-file or error condition is encountered while reading from stream, or if nitems items have been read. fread leaves the file pointer in stream, if defined, pointing to the byte follow- ing the last byte read if there is one. fread does not change the contents of the file referred to by stream. fwrite writes at most nitems items of data from the block pointed to by ptr to the named output stream stream. It returns the number of items actually written. fwrite stops writing when it has written nitems items of data or if an error condition is encountered on stream. fwrite does not change the contents of the block pointed to by ptr. If size or nitems is non-positive, no characters are read or written and 0 is returned by both fread and fwrite. RETURN VALUES fread and fwrite return the number of elements read on success, 0 on failure. SEE ALSO \#read\#, \#write\#, \#fopen\#, \#getc\#, \#gets\#, \#putc\#, \#puts\#, \#printf\#, \#scanf\#\end screen( capsensitive("fseek"), capsensitive("ftell"), capsensitive("rewind")) NAME fseek, ftell, rewind - reposition a stream SYNOPSIS #include <stdio.h> fseek(FILE *stream, long offset, int mode); long ftell(FILE *stream); void rewind(FILE *stream); DESCRIPTION fseek sets the position of the next input or output operation on the stream. The parameter offset determines the new position according to the parameter mode: SEEK_SET (0): offset bytes from the start of the file SEEK_CUR (1): offset bytes further than the current position SEEK_END (2): offset bytes from the end of the file rewind is equivalent to fseek(stream, 0L, 0), except that no value is returned. ftell returns the offset of the current byte relative to the beginning of the file associated with the named stream. fseek and rewind undo any effects of \#ungetc\#. After fseek or rewind, the next operation on a file opened for update may be either input or output. RETURN VALUES fseek returns 0 on success, -1 on failure. ftell returns a position >= 0 on success, -1 on failure. SEE ALSO \#lseek\#, \#fopen\#, \#popen\#, \#ungetc\#\end screen( capsensitive("ftw")) NAME ftw - walk a file tree SYNOPSIS #include <ftw.h> int ftw(char *path, int (*fn)(char *, struct stat *, int), int depth); DESCRIPTION ftw recursively descends the directory hierarchy rooted in path. For each object in the hierarchy, ftw calls the user-supplied function fn, passing it a pointer to a null-terminated character string containing the name of the object, a pointer to a stat structure containing information about the object, and an integer. Possible values of the integer, defined in the <ftw.h> header file, are FTW_F for a file, FTW_D for a directory, FTW_DNR for a directory that cannot be read, and FTW_NS for an object for which \#stat\# could not successfully be executed. If the integer is FTW_DNR, descendants of that directory will not be processed. An example of an object that would cause FTW_NS to be passed to fn would be a file in a directory with read but without execute (search) permission. ftw visits a directory before visiting any of its descendants. The tree traversal continues until the tree is exhausted, an invocation of fn returns a nonzero value, or some error is detected within ftw (such as an I/O error). If the tree is exhausted, ftw returns zero. If fn returns a nonzero value, ftw stops its tree traversal and returns whatever value was returned by fn. If ftw detects an error, it returns -1, and sets the error type in errno. ftw uses one file descriptor for each level in the tree. The depth argument limits the number of file descriptors so used. If depth is zero or negative, the effect is the same as if it were 1. Depth must not be greater than the number of file descriptors currently available for use. ftw will run more quickly if depth is at least as large as the number of levels in the tree. SEE ALSO \#stat\# NOTES Note that MiNT limits each process to 32 file descriptors. Since three are normally used for standard input, output and error output, only few remain. C library functions like this are usually only found after a similar version has already been written by the programmer. BUGS Because ftw is recursive, it is possible for it to terminate with a memory fault when applied to very deep file structures. Symbolic links are reported to the user-supplied function as FTW_F.\end screen( capsensitive("getgrent"), capsensitive("getgrgid"), capsensitive("getgrnam"), capsensitive("setgrent"), capsensitive("endgrent"), capsensitive("fgetgrent")) NAME getgrent, getgrgid, getgrnam, setgrent, endgrent, fgetgrent - get group file entry SYNOPSIS #include <stdio.h> #include <grp.h> struct group *getgrent(void); struct group *getgrgid(int gid); struct group *getgrnam(const char *name); void setgrent(void); void endgrent(void); struct group *fgetgrent(FILE *f); DESCRIPTION getgrent, getgrgid and getgrnam each returns a pointer to an object containing the broken-out fields of a line in the /etc/group file. Each line in the file contains a "group" structure, declared in the <grp.h> header file: struct group { char *gr_name; /* name of the group */ char *gr_passwd; /* encrypted password */ gid_t gr_gid; /* numerical group ID */ char **gr_mem; /* array of member names */ }; getgrent when first called returns a pointer to the first group structure in the file; thereafter, it returns a pointer to the next group structure in the file; so successive calls can be used to search the entire file. getgrgid searches from the beginning of the file until a numerical group ID is found matching gid is found and returns a pointer to the particular structure in which it was found. Thus, it cannot be found to search for several groups having duplicate numerical group IDs. getgrnam searches from the beginning of the file until a group name matching name is found and returns a pointer to the particular structure in which it was found. If an EOF or an error is encountered on reading, getgrent, getgrgid and getgrnam return a NULL pointer. A call to setgrent has the effect of rewinding the group file to allow repeated searches. endgrent may be called to close the group file when processing is complete. fgetgrent returns a pointer to the next group structure in the stream f, which matches the format of /etc/group. FILES /etc/group SEE ALSO \#getlogin\#, \#getpwent\# NOTES All information is contained in a static area, so it must be copied if it is to be saved. These routines cannot handle groups with over 128 members. These routines expect the group file to be of type text, and can therefore read both DOS and UN*X format files. fgetgrent is not standard, but is available on System V. For group files, there's no equivalent to \#putpwent\#. The password field of groups is seldom used.\end screen( capsensitive("getlogin")) NAME getlogin - get login name SYNOPSIS #include <unistd.h> char *getlogin(void); DESCRIPTION getlogin returns a pointer to the user's login name. This is determined in the following way: - The name for the current userid is read from the password file using \#getuid\# and \#getpwuid\#. - If this fails, the environment variable USER is read. - If this fails, "user" is returned. This call returns a pointer to a dynamically allocated area of memory. Consecutive calls will return the same pointer. SEE ALSO \#cuserid\#, \#getgrent\#, \#getpwent\#, \#getpwuid\#, \#getuid\# NOTES The method used to determine the user's login name, getpwuid(getuid()), is supposed to be the most reliable way. It will fail if several users have identical numerical userids, though. On System V, this routine will read from /etc/utmp in order to find out the current user's login name. This method can be fooled by changing the terminal associated with standard input, and thus is no viable alternative.\end screen( capsensitive("getopt"), capsensitive("optarg"), capsensitive("optind"), capsensitive("opterr")) NAME getopt - get option letter from argument vector SYNOPSIS #include <unistd.h> int getopt(int argv, char * const *argv, const char *optstring); extern char *optarg; extern int optind; extern int opterr; DESCRIPTION getopt returns the next option letter in argv that matches a letter in optstring. It supports all the rules of the UN*X System V command syntax standard (see the section RULES below). All new programs that wish to adhere to the command syntax standard should use getopt to parse positional parameters and check for options that are legal for that command. optstring must contain the option letters the command using getopt will recognize; if a letter is followed by a colon, the option is expected to have an argument, or group of arguments, which must be separated from it by white space. optarg is set to point to the start of the option-argument on return from getopt. getopt places in optind the argv index of the next argument to be processed. optind is external and is initialized to 1 before the first call to getopt. When all options have been processed (i.e., up to the first non-option argument), getopt returns EOF. The special option "--" may be used to delimit the end of the options; when it is encountered, EOF will be returned, and "--" will be skipped. DIAGNOSTICS getopt prints an error message on standard error and returns a question mark (?) when it encounters an option letter not included in optstring or no option-argument after an option that expects one. This error message may be disabled by setting opterr to 0. RULES The UN*X System V command standard contains the following rules: 1. Command names must be between two and nine characters long. 2. Command names must include only lower-case letters and digits. 3. Option names must be one character long. 4. All options must be preceded by "-". 5. Options with no arguments may be grouped with a single "-". 6. The first option-argument following an option must be preceded by white space. 7. Option-arguments cannot be optional. 8. Groups of option-arguments following an option must be either be separated by commas or separated by white space and quoted (e.g., -o xxx,z,yy or -o "xxx z yy"). 9. All options must precede operands on the command line. 10. "--" may be used to indicate the end of the options. 11. The order of the options relative to another should not matter. 12. The relative order of the operands may effect their significance in ways determined by the command with which they appear. 13. "-" preceded and followed by white space should only be used to mean standard input. getopt supports rules 3-10 above; the enforcement of the other rules must be done by the command itself. EXAMPLE The following code fragment shows how one might process the arguments for a command that can take the mutually exclusive options 'a' and 'b', and the option 'o', which requires an option-argument. #include <stdio.h> #include <stdlib.h> #include <unistd.h> extern char *optarg; void main(int argc, char *argv[]) { int c, aflg = 0, bflg = 0, errflg = 0; char *ofile = NULL; while ((c = getopt(argc, argv, "abo:")) != EOF) switch (c) { case 'a': if (bflg != 0) errflg++; else aflg++; break; case 'b': if (aflg != 0) errflg++; else bflg++; break; case 'o': ofile = optarg; break; case '?': errflg++; } if (errflg != 0) { fprintf(stderr, "Usage:...\\n"); exit(1); } ... } NOTES getopt cannot be used for complicated context-sensitive argument vector parsing. The UN*X System V standard may seem too restrictive; for instance, in the above example, '-ofile' is not allowed ('-o file' is). Some systems return -1 instead of EOF; this may actually make a difference on some systems.\end screen( capsensitive("getpass")) NAME getpass - read a password SYNOPSIS #include <unistd.h> char *getpass(const char *prompt); DESCRIPTION getpass reads up to a newline or EOF from standard input (TOS) or /dev/tty (MiNT), after prompting on the standard error output with the null-terminated string prompt and disabling echoing. A pointer is returned to a null-terminated string of at most PASS_MAX characters. PASS_MAX is defined in <limits.h> and has curently been set to 8. WARNING getpass uses <stdio.h>, which may cause an unexpected increase in the size of a program not otherwise using standard I/O. The return value points to static data whose contents is overwritten by each call.\end screen( capsensitive("getrlimit"), capsensitive("setrlimit")) NAME getrlimit, setrlimit - control maximum system resource con- sumption SYNOPSIS #include <sys/time.h> #include <sys/resource.h> int getrlimit(int kind, struct rlimit *rlp); int setrlimit(int kind, struct rlimit *rlp); DESCRIPTION Limits on the consumption of system resources by the current process and each process it creates may be obtained with the getrlimit call, and set with the setrlimit call. These functions only work for real if MiNT is active. The following resource parameters are allowed: RLIMIT_CPU the maximum amount of cpu time (in milliseconds) to be used by each process. RLIMIT_FSIZE the largest size, in bytes, of any single file that may be created. RLIMIT_DATA the maximum size, in bytes, of the data the process may allocate with \#Malloc\#. RLIMIT_STACK the maximum size, in bytes, of the stack segment for a process. RLIMIT_CORE the largest size, in bytes, of a core file that may be created. RLIMIT_RSS the maximum size, in bytes, allowed for the process. Of these, only the RLIMIT_CPU, RLIMIT_DATA and RLIMIT_RSS parameters are supported. The others do nothing. The UN*X parameter RLIMIT_NOFILE is not available in the header file at all. Also, the value of the RLIMIT_CPU parameter is in milliseconds, while the UN*X version is specified in seconds. A resource limit is specified as a soft limit and a hard limit. When a soft limit is exceeded a process receives a signal SIGXCPU if the cpu time is exceeded; memory allocations will fail if RLIMIT_DATA or RLIMIT_RSS is exceeded. Hard limits are not enforced at all. The struct rlimit is defined as follows: struct rlimit { long rlim_cur; /* current (soft) limit */ long rlim_max; /* hard limit (not supported) */ }; Contradicting the UN*X version, any process may increase its limits at will. An "infinite" value for a limit is defined as RLIM_INFINITY (0x7fffffff). RETURN VALUES getrlimit and setrlimit return: 0 on success. -1 on failure; errno is set to EINVAL. SEE ALSO \#Psetlimit\# - this system call is used in the implementation of these routines. \#getrusage\#, \#signal\# BUGS These functions are so different from their UN*X equivalents that they are practically worthless.\end screen( capsensitive("gets"), capsensitive("fgets")) NAME gets, fgets - get a string from a stream SYNOPSIS #include <stdio.h> char *gets(char *s); char *fgets(char *s, int n, FILE *stream); DESCRIPTION gets reads characters from the standard input stream, stdin, into the array pointed to by s, until a new-line character is read or an end-of-file condition is encountered. The new-line character is discarded and the string is terminated with a null character. fgets reads character from the file stream into the array pointed to by s, until n-1 characters are read, or a new-line character is read and transferred to s, or an end-of-file condition is encountered. The string is then terminated with a null character. SEE ALSO \#ferror\#, \#fopen\#, \#fread\#, \#getc\#, \#scanf\# RETURN VALUES If end-of-file is encountered and no characters have been read, no characters are transferred to s and a NULL pointer is returned. If a read error occurs, such as trying to use these functions on a file that has not been opened for reading, a NULL pointer is returned. Otherwise s is returned.\end screen( capsensitive("getwd"), capsensitive("getcwd")) NAME getwd, getcwd - get path-name of current working directory SYNOPSIS #include <unistd.h> char *getwd(char *buf); char *getcwd(char *buf, int size); DESCRIPTION getcwd returns a pointer to the current directory path name. The value of size is the maximum length of the name to be returned. If buf is a NULL pointer, getcwd will obtain size bytes of space using \#malloc\#. It is up to the calling process to free this buffer. getwd is equivalent to getcwd(buf, PATH_MAX). Since PATH_MAX is the length of the longest path name allowed, this buffer should always be sufficient. Still, the use of this function is discouraged, since it is not specified in POSIX and may therefore be unavailable on other systems. SEE ALSO \#chdir\#, \#malloc\# \#Dgetcwd\#, \#Dgetdrv\#, \#Dgetpath\#; these system calls are used in the implementation of these routines. RETURN VALUES These functions return NULL is buf is NULL and no memory could be allocated; otherwise, a pointer to buf is returned. NOTES On TOS and MiNT before 0.96, the size parameter to getcwd is only used for allocating memory; this functions are not yet safe, i.e. buf may overflow. On UN*X System V.3, the getcwd function was implemented using popen() and the pwd command! There had to be a better way...\end screen( capsensitive("isatty")) NAME isatty - is this file desciptor a terminal device SYNOPSIS #include <unistd.h> int isatty(int fildes); DESCRIPTION isatty returns 1 if file descriptor fildes is associated with a terminal device, 0 otherwise. SEE ALSO \#ttyname\# NOTE The current implementation makes use of the \#Fseek\# system call, which may explain the appearance of the \#Fseek\# call in system debug messages whenever a program tries to determine whether it is writing to a file or to a tty.\end screen( capsensitive("malloc"), capsensitive("free"), capsensitive("realloc"), capsensitive("calloc"), capsensitive("alloca") ) NAME malloc, free, realloc, calloc, alloca - memory allocator SYNOPSIS #include <stdlib.h> void *malloc(size_t size); void free(void *ptr); void *realloc(void *ptr, size_t size); void *calloc(size_t num_elems, size_t elem_size); void *alloca(size_t size); DESCRIPTION These routines provide a general-purpose memory allocation package. They maintain a table of free blocks for efficient allocation and coalescing of free storage. When there is no suitable space already free, the allocation routines call \#Malloc\# to get more memory from the system. Each of the allocation routines returns a pointer to space suitably aligned for storage of any type of object. Each returns a NULL pointer if the request cannot be completed or if an area of size zero is requested. malloc returns a pointer to a block of at least size bytes. free releases a previously allocated block. Its argument is a pointer to a block previously allocated by malloc, calloc or realloc. realloc changes the size of a block referenced to by ptr to size bytes and returns a pointer to the (possibly moved) block. The contents will be unchanged up to the lesser of the new and old sizes. If unable to honor a reallocation request, realloc leaves it first argument unaltered. Using realloc with a block freed before is an error. realloc(NULL, size) is the same as malloc(size). realloc(ptr, 0) is the same as free(ptr). calloc uses malloc to allocate space for an array of num_elems elements of size elem_size, initialises the space to zeros, and returns a pointer to the initialised block. alloca allocates size bytes of space in the stack frame of the caller, and returns a pointer to the allocated block. This temporary space is automatically freed when the caller returns. Note that if the allocated block is beyond the current stack limit, the resulting behavior is undefined. RETURN VALUES On success, malloc, calloc, realloc and alloca return a pointer to space suitably aligned for storage of any type of object. On failure, they return NULL. SEE ALSO \#Malloc\#, \#getrlimit\# WARNINGS On UN*X machines, malloc and realloc return a non-NULL pointer if size is 0, and calloc returns a non-NULL pointer if num_elems or elem_size is 0. The mintlibs follow the ANSI-C standard and return NULL in these circumstances. alloca is machine-, compiler-, and most of all, system- dependent. Its use is strongly discouraged. NOTES GNU software is uncommonly fond of alloca. To use alloca with Pure-C in the current version of the mintlibs, the caller must be compiled with the -S option set or the program will crash.\end screen( capsensitive("mktemp")) NAME mktemp - make a unique file name SYNOPSIS #include <unistd.h> char *mktemp(char *template); DESCRIPTION mktemp creates a unique file name, typically in a temporary filesystem, by replacing template with a unique file name, and returns the address of template. The string in template should contain a file name with six trailing Xs; mktemp replaces the Xs with a number and the current process ID. The number will be chosen so that the resulting name does not duplicate an existing file. RETURN VALUES mktemp returns a pointer to the changed template on success, and NULL on failure. SEE ALSO \#getpid\#, \#open\#, \#tmpfile\#, \#tmpnam\# NOTES The related UN*X function mkstemp is currently not available in the mintlibs. mktemp actually changes the template string which you pass; this means that you cannot use the same template string more than once - you need a fresh template for every unique file you want to open. When mktemp is creating a new unique filename it checks for the prior existence of a file with that name. This means that if you are creating more than one unique filename, it is bad practice to use the same root template for multiple invocations of mktemp. The current process id is used only if there is enough room in the string and MiNT is active. BUGS It is possible to run out of numbers.\end screen( capsensitive("perror"), capsensitive("errno"), capsensitive("sys_errlist"), capsensitive("sys_nerr"), capsensitive("strerror")) NAME perror, errno, sys_errlist, sys_nerr, strerror - system error messages SYNOPSIS #include <stdio.h> void perror(const char *s); #include <errno.h> extern int errno; extern char *sys_errlist[]; extern int sys_nerr; #include <string.h> char *strerror(int errnum); DESCRIPTION perror produces a message on the standard error output, describing the last error encountered during a call to a system or library function. The argument string s is printed first, then a colon and a blank, then the message and a new-line. (However, if s is NULL or s is an empty string the colon is not printed.) To be of most use, the argument string should include the name of the program that incurred the error. The error number is taken from the external variable errno, which is set when errors occur but not cleared when non-erroneous calls are made. To simplify variant formatting of messages, the array of message strings sys_errlist is provided; errno can be used as an index into this table to get the message string without the new-line. sys_nerr is the number of messages in the table; it should be checked because new error codes may be added to the system before they are added to the table. The string function strerror takes an error code as its argument and returns the corresponding message; since it checks sys_nerr, it may be easier of safer to use than sys_errlist. NOTES On UN*X, the string s may be empty, but may not always be NULL. Not all UN*X or POSIX error codes are supported by the mintlibs.\end screen( capsensitive("psignal"), capsensitive("signal_names"), capsensitive("sys_siglist")) NAME psignal, sys_siglist, signal_names - system signal messages SYNOPSIS #include <unistd.h> void psignal (int sig, const char *s); #include <siglist.h> extern char *sys_siglist[]; extern char *signal_names[]; // Should not be used DESCRIPTION psignal produces a message on the standard error output describing the indicated signal. The argument string s is printed first, then a colon and a blank, then the name of the signal and a new-line. (However, if s is NULL or s is an empty string the colon is not printed.) To be of most use, the argument string should include the name of the program that incurred the signal. The signal number should be from among those found in <signal.h>. To simplify variant formatting of messages, the array of messages sys_siglist is provided; the signal number can be used as an index into this table to get the signal name without the new-line. The constant NSIG defined in the include file <signal.h> is the number of messages provided for in the table. The array of signal names signal_names has also been provided; it is there only for backward compatibility purposes, and should not be used. NOTES On UN*X, the string s may be empty, but may not always be NULL. MiNT signals are rather different from UN*X and POSIX.\end screen( capsensitive("puts"), capsensitive("fputs")) NAME puts, fputs - put a string on a stream SYNOPSIS #include <stdio.h> int puts(const char *s); int fputs(const char *s, FILE *stream); DESCRIPTION puts writes the null-terminated string pointed to by s, followed by a new-line character, to the standard output stream stdout. fputs writes the null-terminated string pointed to by s to the named output file stream. Neither function writes the terminating null character. SEE ALSO \#ferror\#, \#fopen\#, \#fread\#, \#printf\#, \#putc\# RETURN VALUES These routines return EOF on error. Otherwise, the number of bytes written is returned. NOTE puts appends a new-line character while fputs does not.\end screen( capsensitive("rand"), capsensitive("srand")) NAME rand, srand - simple random number generator SYNOPSIS #include <stdlib.h> int rand(void); void srand(unsigned int seed); DESCRIPTION rand is a simple random number generator that returns pseudo- random numbers in the range 0 to 2^15 - 1 (16-bit integers) or 0 to 2^31 - 1 (32-bit integers). The period of this random number generator is 2^31 - 2, irrespective of the integer size. srand can be called at any time to reset the random number generator to a random starting point. The generator is initially seeded with a value of 1. SEE ALSO \#random\#, \#srandom\# NOTES Although \#random\# is slower, it is a far better random number generator. It seems that BSD UN*X srand returns the previous seed.\end screen( capsensitive("random"), capsensitive("srandom"), capsensitive("initstate"), capsensitive("setstate")) NAME random, srandom, initstate, setstate - improved random number generator; routines for changing generators SYNOPSIS #include <unistd.h> long random(void); void srandom (unsigned int seed); char * initstate (unsigned int seed, char *arg_state, int n); char * setstate (char *arg_state); DESCRIPTION random is a good random number generator returning pseudo- random numbers in the range from 0 to 2^31 - 1. The random number generator has a very large period. random/srandom have (almost) the same calling sequence and initialization properties as \#rand\#/\#srand\#. The difference is that \#rand\# produces a much less random sequence, while all the bits generated by random are useable. The initstate routine allows a state array, passed in an argument, to be initialized for future use. The size of the state array (in bytes) is used by initstate to decide how sophisticated a random number generator it should use - the more state, the better the random numbers will be. Good values for the amount of state information are 32, 64, 128 and 256 bytes. The seed for the initialization (which specifies a starting point for the random number sequence, and provides for restarting at the same point) is also an argument. initstate returns a pointer to the previous state information array. Once a state array has been initialized, the setstate routine provides for rapid switching between states. setstate returns a pointer to the previous state array; its argument state array is used for further random number generation until the next call to initstate or setstate. Once a state array has been initialized, it may be restarted at a different point either by calling initstate (with the desired seed, the state array, and its size) or by calling both setstate (with the state array) and srandom (with the desired seed). The advantage of calling both setstate and srandom is that the size of the state array does not have to be remembered after it is initialized. SEE ALSO \#rand\#, \#srand\# NOTES See the source file (random.c) for complete information and comments on the workings of the random number generator. random is slower than \#rand\#.\end screen( capsensitive("qsort") ) NAME qsort - quicker sort SYNOPSIS #include <stdlib.h> qsort(void *base, size_t total_elems, size_t elem_size, int (*compare)(const void *one, const void *two)); DESCRIPTION qsort is an implementation of the quicker-sort algorithm. It sorts a table of data in place. - base points to the element at the base of the table. - total_elems is the number of elements in the table. - elem_size is the size, in bytes, of each element in the table. - compare is the name of the comparison function, which is called with two arguments that point to the elements being compared. As the function must return an integer less than, equal to, or greater than zero, so must the first argument to be considered be less than, equal to, or greater than the second. EXAMPLE The following program sorts a simple array: static int intcompare(const void *i, const void *j) { int *one, *two; one = (int *)i; two = (int *)j; return (*one - *two); } void main(void) { int a[10]; int i; a[0] = 9; a[1] = 8; a[2] = 7; a[3] = 6; a[4] = 5; a[5] = 4; a[6] = 3; a[7] = 2; a[8] = 1; a[9] = 0; qsort(a, 10, sizeof(int), intcompare); for (i = 0; i < 10; i++) printf(" %d", a[i]); printf("\\n"); } SEE ALSO \#bsearch\# NOTES The comparison function need not compare every byte, so arbitrary data may be contained in the elements in addition to the values being compared. The order in the output of two items which compare as equal is unpredictable.\end screen( capsensitive("setbuf"), capsensitive("setvbuf"), capsensitive("setlinebuf")) NAME setbuf, setlinebuf, setvbuf - assign buffering to a stream SYNOPSIS #include <stdio.h> #include <unistd.h> // Only needed for setlinebuf void setbuf(FILE *stream, char *buf); void setlinebuf(FILE *stream); int setvbuf(FILE *stream, char *buf, int type, size_t size); DESCRIPTION setbuf may be used after a stream has been opened but before it is read or written. It causes the array pointed to by buf to be used instead of an automatically allocated buffer. If buf is the NULL pointer input/output will be completely unbuffered. A constant BUFSIZ, defined in <stdio.h>, tells how big an array is needed: char buf[BUFSIZ]; setlinebuf may be used after a stream has been opened and after it is read or written. It changes the buffering on stream from block/unbuffered to line buffered. setvbuf may be used after a stream has been opened but before it is read or written. The type parameter determines how stream will be buffered. Legal values for type (defined in <stdio.h>) are: _IOFBF: causes input/output to be fully buffered. _IOLBF: causes output to be line buffered; the buffer will be flushed when a newline is written, the buffer is full, or input is requested. _IONBF: causes input/output to be fully unbuffered. If buf is not the NULL pointer, the array it points to will be used for buffering, instead of an automatically allocated buffer. size specifies the size of the buffer to be used. The constant BUFSIZ in <stdio.h> is suggested as a good buffer size. If input/output is unbuffered, buf and size are ignored. By default, output to a terminal is line buffered and all other input/output is fully buffered. SEE ALSO \#fopen\#, \#getc\#, \#putc\# RETURN VALUES setvbuf returns a non-zero value if an illegal value for type or size is provided; otherwise, it will return zero. NOTES A common source of error is allocating buffer space as an "automatic" variable in a code block, and then failing to close the stream in the same block. setlinebuf is available on BSD UN*X, and not on System V.\end screen( capsensitive("sleep"), capsensitive("usleep")) NAME sleep, usleep - suspend execution for interval SYNOPSIS #include <unistd.h> unsigned sleep(unsigned seconds); void usleep(unsigned long usec); // should be of type unsigned long DESCRIPTION The current process is supended from execution for the number of seconds (sleep) or microseconds (usleep) specified by the argument. Sleep returns early if a signal is caught; after the signal handler has returned, sleep will return the "unslept" amount. If no signal was caught, and after the full amount of of time (and possibly somewhat longer) has passed, execution is resumed. SEE ALSO \#alarm\# \#Fselect\#, \#Pause\#, \#Psigpause\#, \#Talarm\# NOTES On UN*X, usleep is of type unsigned int. Under TOS or MiNT before 0.95, these routines do a busy wait until enough time has passed.\end screen( capsensitive("system")) NAME system - execute a command, passed a string SYNOPSIS #include <unistd.h> int system(const char *cmd); DESCRIPTION system executes the command in the string, and waits until it terminates. The first word in the string is the name of the program to be executed; this program is searched in the current directory and on the directories set in the environment variable PATH. The normal extensions ".ttp", ".tos" and ".prg" are tried when the program is being searched. If the rest of the string contains unquoted '<' or '>' characters, standard input or standard output for the command to be run is redirected to the file with the filename following the '<' or '>'. The remaining part of the string is passed to the program as a command line. This routine is implemented using \#spawnvp\#. RETURN VALUES system(NULL) returns 1 as an indication system is supported. When a valid command line is passed, system returns: -1 when out of memory. 2 when the redirection of stdin or stdout fails. The return value of the program called when successful. SEE ALSO \#spawnvp\#, \#execve\#, \#popen\# NOTE On UN*X systems, this starts up the shell /bin/sh as a child process. The shell executes the command passed to system. Thus, on UN*X systems, one can pass a more complicated command line to system, for instance one containing pipes or shell scripts. This may cause some problems when porting UN*X programs to the Atari.\end screen(capsensitive("tmpfile")) NAME tmpfile - create a temporary file SYNOPSIS #include <stdio.h> FILE *tmpfile(void); DESCRIPTION tmpfile creates a temporary file using a name generated by \#tmpnam\#, and returns a corresponding FILE pointer. If the file cannot be opened, a NULL pointer is returned. The file will automatically be deleted when the process using it terminates. The file is opened in binary mode for update ("w+b"). SEE ALSO \#fopen\#, \#mktemp\#, \#tmpnam\#, \#unlink\# NOTE When MiNT is active, and the filesystem supports it, the temporary file will be unlinked while it is open. Otherwise, the file will be visible to this process and other processes and will be unlinked when the process terminates using a procedure registered with \#atexit\#. Thus, if MiNT is not active or if the filesystem used does not support unlinking an open file, the temporary file may remain after abnormal program termination.\end screen( capsensitive("tmpnam")) NAME tmpnam - create a name for a temporary file SYNOPSIS #include <stdio.h> char *tmpnam(char *buf); DESCRIPTION This function generates a file name that can safely be used for a temporary file. tmpnam always tries to generate a file name in a directory meant for temporary files; it tries to determine such a directory by checking the environment variables TEMP, TMPDIR, TMP and TEMPDIR, successively; if this search fails, the current directory is used. If buf is NULL, tmpnam leaves its result in an internal static area and returns a pointer to that area. The next call to tmpnam will destroy the contents of the area. If buf is not NULL, it is assumed to be the address of an buffer area; tmpnam places its result in that buffer and returns buf. SEE ALSO \#creat\#, \#fopen\#, \#mktemp\#, \#tmpfile\#, \#unlink\# NOTES The related UN*X function tempnam is currently not available in the mintlibs. This function generates a different file name each time it is called. Files created using this function and either \#fopen\# or \#creat\# are temporarily only in the sense that they reside in a directory intended for temporary use, and their file names are unique. It is the user's responsibility to use \#unlink\# to remove the file when its use is ended.\end screen( capsensitive("ttyname")) NAME ttyname - find name of a terminal SYNOPSIS #include <unistd.h> char *ttyname(int fildes); DESCRIPTION ttyname returns a pointer to a string containing the null- terminated path name of the terminal device associated with file descriptor fildes. A NULL pointer is returned if fildes does not describe a terminal device. SEE ALSO \#isatty\# NOTES If MiNT is not active or a version of MiNT before 0.9 is used, either /dev/aux or /dev/con is returned. If MiNT 0.9 or later is used and no terminal name could be found, /dev/tty is returned. The return value points to static data whose contents is overwritten by each call.\end